---
title: 实验性 Markdown 标题 ID 兼容性
sidebar:
  label: Markdown 标题 ID 兼容性
i18nReady: true
---

import Since from '~/components/Since.astro'

<p>

**类型：** `boolean`<br />
**默认值：** `false`<br />
<Since v="5.5.0" />
</p>

`experimental.headingIdCompat` 标志使 Astro 为 Markdown 标题生成的 ID 与 GitHub 和 npm 等常见平台兼容。

要启用标题 ID 兼容性，请在 Astro 配置中将该标志设置为 `true`：

```js title="astro.config.mjs" ins={4-6}
import { defineConfig } from "astro/config"

export default defineConfig({
  experimental: {
    headingIdCompat: true,
  }
})
```

## 用法

该实验性标志允许你在 Markdown 标题以特殊字符结尾时，保留 ID 尾部的连字符（-），从而生成与其他常见平台兼容的 ID。它无需特定用法，仅影响 Astro 对使用 Markdown 语法编写的标题生成 ID 的方式。

与其他平台一样，Astro 使用流行的 [`github-slugger`](https://github.com/Flet/github-slugger) 包将 Markdown 标题的文本内容转换为 slug 以用于 ID。此实验性标志允许你省略 Astro 的额外默认处理步骤——即当标题以特殊字符结尾时，自动移除 ID 末尾的连字符。

例如以下 Markdown 标题：

```md
## `<Picture />`
```

在 Astro 中默认情况下将生成以下 HTML：

```html "picture"
<h2 id="picture"><code>&lt;Picture /&gt;</h2>
```

使用 `experimental.headingIdCompat`, 相同的 Markdown 将生成以下 HTML，与 GitHub 等平台相同：

```html "picture-"
<h2 id="picture-"><code>&lt;Picture /&gt;</h2>
```

在未来的主要版本中，Astro 将默认使用兼容的 ID 样式，但你可以提前使用 `experimental.headingIdCompat` 标志提前启用这一未来行为。

## 与 `rehypeHeadingIds` 插件一起使用

如果你直接[使用 `rehypeHeadingIds` 插件](/zh-cn/guides/markdown-content/#标题-id-与插件)，需在 Astro 配置中传入插件时启用兼容模式：

```js title="astro.config.mjs" {8}
import { defineConfig } from 'astro/config';
import { rehypeHeadingIds } from '@astrojs/markdown-remark';
import { otherPluginThatReliesOnHeadingIDs } from 'some/plugin/source';

export default defineConfig({
  markdown: {
    rehypePlugins: [
      [rehypeHeadingIds, { headingIdCompat: true }],
      otherPluginThatReliesOnHeadingIDs,
    ],
  },
});
```
